TODO

Put your name next to an item if you are working on it.

1. (jay) org.rhq.server.control.command.Install.waitForRHQServerToInitialize() should at least spit out a warning if its taking too long or abort if its taking too long.

2. (jay) See if that same waitForRHQServerToInitialize() method above can use our common jboss-as-dmr client jar - this is how our installer checks to see if the server is up and running. We'd need to slurp in rhq-server.properties to get the management.native port and the jboss.bind.address so we know what addr/port the AS7 management engine is listening to. Rather than look at the log file to see if its started, we can make a CLI call via our JBossASClient stuff to see if the EAR is deployed - its pretty simple:

   DeploymentJBossASClient client = new DeploymentJBossASClient(MCCHelper.getModelControllerClient(<host>, <port>));
   boolean isDeployed = client.isDeployment("rhq.ear");
   return isDeployed;

   This means we have to put the jboss-as-dmr-client.jar as a module dependency in the rhqctl module (aka "org/rhq/rhq-server-control" module). No biggie.

3. need to add support for new main command to rhqctl: upgrade

4. rhqctl upgrade needs to support "--agent-dir" for supporting old 4.7- agents installed elsewhere

5. rhqctl upgrade will assume it is upgrading everything

6. rhqctl upgrade needs to read the old server's rhq-server.properties and merge it with the new out of box properties for the new one. See org.rhq.core.util.PropertiesFileUpdate for how we can maniuplate .properties while maintaining order and comments.

7. rhqctl install always installs an agent if you specify --storage but not --server - this means there may not be a server running on that box, so we need a easy way for users to tell us where the server is for the agent to talk to. We already have --agent-preference rhq.agent.server.bind-address=<host> but that is hard to remember and not user friendly. So perhaps we need to support "--agent-server-endpoint" so the user can use that to tell us what server the agent can talk to. I don't necessarily think we need to "require" this. Because we support the "rhq.agent.server.alias" thing in the agent which means agent machines can have a DNS alias setup that tells what server it can register on - see agent-configuration.xml comments on this. Note: --agent-server-endpoint can have a value of things like "localhost:7080" which we assume is HTTP (that is, "servlet" protocol in Jboss/Remoting parlance). However, we need to support HTTPS (sslservlet) and the "socket" or "sslsocket" protocol that the server might be using, so that's where --agent-server-endpoint needs to support the JBoss/Remoting format of endpoint (which is really just a URL). We'll just have to parse the value properly into its parts (transport, port, bind-address, transport-params) and set the preferences accordingly

8. (mazz) rhqctl install --agent should be told to only install, but not start, the agent. This gives the user a chance to configure the agent for things like SSL keystore/truststores before starting the agent the first time. So "rhqctl install --agent --agent-no-start" should be supported (--agent-no-start should also be available when doing "rhqctl install --storage" or "rhq install" too).

9. (mazz) we need to turn OFF agent-auto-update in the agent preferences during install

10. (mazz) we need rhqctl install to accept --storage-data-root-dir directory and we need to collapse the storage installer's 3 data directory settings into a single one and use that as the base for the 3 different data dirs.

11. (mazz) storage install should fail if the data directories are not empty Stefan pointed this out. Let's say I install RHQ 4.8. Then later decide to re-install on the same machine. I blow away my relational db or point to a different db. If the old data directory is reused, we will end up with data from schedules from a previous install which could be schedule that no longer exist in the new install.

12. I think we need better help text and text below describing "rhqctl install --storage" - because this implies --agent. But no where here or in the help does it even mention this. Perhaps the option should be called --storage-and-agent ??

13. (mazz) Remove the rhqctl --install --storage-dir and --agent-dir options. The locations will be fixed under <rhq-install-root>/rhq-storage and <rhq-install-root>/rhq-agent.

14. One more thing about the agent install. We need to support the RUN_AS and RUN_AS_ME stuff for the win service. How will this be done? Will these env vars need to be defined prior to install?

15. (mazz) Before we start the out-of-box server during install, check to see if port 9999 is up - if it is, we need to abort and say "looks like you already have an EAP instance running - please shut it down in order to install the server"

• when upgrading from 4.7-, we are either updating a box with a server AND an agent, or a box with only a server. We will not be using rhqctl to upgrade only an agent - that's what teh agent binary update jar is for. This is not an action item - just something to remember and keep in mind.

Overview

This documents provides details on the RHQ Control script, rhqctl. The purpose of the control script is to provide basic lifecycle management of any RHQ services installed on a machine. Within the context of this document an RHQ service refers specifically to one of the RHQ server, RHQ agent, or RHQ storage node. Basic lifecycle management includes,

• Installing

• Starting

• Stopping

• Checking status (to see whether or not services are running)

• Starting in console mode (i.e., in the foreground)

A primary objective of the control script is usability. As such rhqctl has only a handful of commands and a limited number of options. To the greatest extent possible, the script should figure out what it needs to do without additional user input or configuration. For example, suppose I invoke the script with the start command and no options. The script will determine  what services are installed on the machine and for each service that is not running, the script will start the service.

Installation

You currently have to build RHQ from source to get the control script. Specifically, you need to build the [feature/cassandra-backend|] branch. The script can then be accessed from <RHQ_ROOT>/modules/enterprise/server/appserver/target/rhq-server-4.7.0-SNAPSHOT.zip. Unzip the RHQ server and you will find the script at <rhq-install-dir>/bin/rhqctl.

Commands

The section gives an overview of basic usage and the commands that rhqctl supports. To see a list of supported command along with basic help information run the script without any arguments.

$ ./rhqctl
13:02:58,714 INFO  [org.jboss.modules] JBoss Modules version 1.1.1.GA
usage: rhqctl <cmd> [options]

where <cmd> is one of:
 console <[options]>   Starts an RHQ service in the foreground. Only one
                       of the following options should be specified.
 install <[options]>   Installs RHQ services.
 start <[options]>     Starts RHQ services.
 status <[options]>    Check status of RHQ services
 stop <[options]>      Stops RHQ services

The control script does not perform the work involved with each of these commands; rather, it delegates to the appropriate scripts for each of the RHQ services.

$ ./rhqctl install -h
20:18:44,898 INFO  [org.jboss.modules] JBoss Modules version 1.1.1.GA
usage: rhqctl install [options]

Installs RHQ services.
    --agent                  Install RHQ agent. The default install
                             directory will be
                             <RHQ_SERVER_HOME>/rhq-agent. Use the
                             --agent-dir option to choose an alternate
                             directory.
    --agent-config <arg>     An alternate XML file to use in place of the
                             default agent-configuration.xml
    --agent-dir <arg>        The directory where the agent will be
                             installed.
    --server                 Install RHQ server
    --server-config <arg>    An alternate properties file to use in place
                             of the default rhq-server.properties
    --storage                Install RHQ storage node. The default install
                             directory will be
                             <RHQ_SERVER_HOME>/rhq-storage. Use the
                             --storage-dir option to choose an alternate
                             directory.
    --storage-config <arg>   A properties file with keys that correspond
                             to option names of the storage installer.
                             Each property will be translated into an
                             option that is passed to the  storage
                             installer. See example.storage.properties for
                             examples.
    --storage-dir <arg>      The directory where the storage node will be
                             installed.

>rhq-storage-installer.bat -h

 -c,--client-port <PORT>          The port on which to listen for client
                                  requests. Defaults to 9142
    --check-status <true|false>   Check the node status to verify that it
                                  is up after starting it. This option is
                                  ignored if the start option is not set.
                                  Defaults to true.
    --commitlog <DIR>             The directory where the storage node
                                  keeps commit log files. Defaults to
                                  /rhq/storage/commitlog.
    --data <DIR>                  The directory where the storage node
                                  keeps data files. Defaults to
                                  /rhq/storage/data.
    --dir <arg>                   The directory where the storage node
                                  will be installed The default directory
                                  will be
                                  c:\work\rhq\dev-container\rhq-storage
 -h,--help                        Show this message.
    --heap-new-size <arg>         The value to use for the new generation
                                  of the heap. This value is passed
                                  directly to the -Xmn option of the Java
                                  executable
    --heap-size <arg>             The value to use for both the min and
                                  max heap. This value is passed directly
                                  to the -Xms and -Xmx options of the Java
                                  executable.
 -j,--jmx-port <PORT>             The port on which to listen for JMX
                                  connections. Defaults to 7299.
 -n,--hostname <HOSTNAME>         The hostname or IP address on which the
                                  node will listen for requests. If not
                                  specified, defaults to the hostname for
                                  localhost.
 -s,--seeds <SEEDS>               A comma-delimited list of hostnames or
                                  IP addresses that serve as contact
                                  points. Nodes use this list to find each
                                  other and to learn the cluster topology.
                                  It does not need to specify all nodes in
                                  the cluster. Defaults to this node's
                                  hostname.
    --saved-caches <DIR>          The directory where the storage node
                                  keeps saved cache files. Defaults to
                                  /rhq/storage/saved_caches.
    --ssl-storage-port <PORT>     The port on which to listen for
                                  encrypted requests from other nodes.
                                  Only used when encryption is enabled.
                                  Defaults to 7101
    --stack-size <arg>            The value to use for the thread stack
                                  size. This value is passed directly to
                                  the -Xss option of the Java executable.
    --start <true|false>          Start the storage node after installing
                                  it on disk. Defaults to true.
    --storage-port <PORT>         The port on which to listen for requests
                                  from other nodes. Defaults to 7100

$ rhqctl install --server

$ rhqctl install --server --agent

$ rhqctl install --storage --storage-dir=/tmp --agent-dir=/tmp

$ rhqctl install --storage --storage-config=/tmp/storage.properties

commitlog=/tmp/rhq/storage/commit_log
data=/tmp/rhq/storage/data
saved-caches=/tmp/rhq/storage/saved_caches

$ ./rhqctl start -h
16:35:10,740 INFO  [org.jboss.modules] JBoss Modules version 1.1.1.GA
usage: rhqctl start [options]

Starts RHQ services.
    --agent     Start RHQ agent
    --server    Start RHQ server
    --storage   Start RHQ storage node

$ ./rhqctl start --storage

$ ./rhqctl.sh start --storage --server

$ ./rhqctl start --agent

$ ./rhqctl stop -h
16:49:53,877 INFO  [org.jboss.modules] JBoss Modules version 1.1.1.GA
usage: rhqctl stop [options]

Stops RHQ services
    --agent     Stop RHQ agent
    --server    Stop RHQ server
    --storage   Stop RHQ storage node

$ ./rhqctl stop --storage

$ ./rhqctl stop --storage --server

$ ./rhqctl stop --agent

$ ./rhqctl status -h
16:58:50,816 INFO  [org.jboss.modules] JBoss Modules version 1.1.1.GA
usage: rhqctl status [options]

Check status of RHQ services
    --agent     Check status of RHQ agent
    --server    Check status of RHQ server
    --storage   Check status of RHQ storage node

$ ./rhqctl status --storage

$ ./rhqctl status --storage --server

$ ./rhqctl status --agent

$ ./rhqctl console -h
16:59:32,058 INFO  [org.jboss.modules] JBoss Modules version 1.1.1.GA
usage: rhqctl console [options]

Starts an RHQ service in the foreground. Only one of the following options
should be specified.
    --agent     Start the RHQ agent in the foreground
    --server    Start the RHQ server in the foreground
    --storage   Start the RHQ storage node in the foreground